Summary

• Refactor local service lifecycle management around a supervisor daemon, typed control API, and backend/WebUI process adapters.
• This addresses cases where backend or WebUI child services become unavailable while the parent supervisor is still running, and keeps CLI/updater lifecycle operations on one control path.

Key Changes

• Added supervisor daemon lifecycle management for backend and WebUI child process groups.
• Added backend health recovery for process exit, lost listener port, and repeated /api/health failures.
• Added WebUI recovery for process exit and lost listener port.
• Added flocks/cli/service_control.py typed control operations for status, stop, restart, WebUI stop/restart, and logs.
• Added flocks/cli/service_config.py as the single owner for service config defaults, CLI/env merge, and control payload serialization.
• Added flocks/cli/service_process.py backend/WebUI process adapters so supervisor policy is separated from process start/stop/probe implementation.
• Updated updater handoff/recovery to use supervisor control operations instead of raw endpoint/payload calls.
• Removed public raw read_control_json / post_control_json usage from CLI/updater callers.

Impact Scope

• User-visible behavior: flocks start/status/stop/restart/logs now operate through the supervisor control plane. Backend and WebUI are restarted by the supervisor when they exit or lose their listener.
• Compatibility / migration: existing backend/WebUI log paths are preserved. Legacy runtime records are only used for one-time cleanup during supervisor startup.
• Configuration / environment: no new required environment variables. Existing host/port CLI options remain supported.
• Dependencies: no new third-party dependencies.
• Performance / resources: adds periodic supervisor health probes with short socket and health-check requests.
• Security / permissions: control API remains local-only through Unix domain socket on Unix/macOS and loopback TCP on Windows.

Business Logic to Review

• flocks/cli/service_supervisor.py: restart policy, pause behavior for upgrade handoff, health failure threshold, and process-group shutdown ordering.
• flocks/cli/service_control.py: typed control API mapping and status parsing.
• flocks/cli/service_config.py: config serialization/deserialization and CLI/env/default precedence.
• flocks/cli/service_process.py: backend/WebUI probe semantics for process exit, listener loss, and backend /api/health failures.
• flocks/updater/updater.py: WebUI stop/restart during upgrade handoff and rollback recovery.

Why This Approach

• The supervisor daemon becomes the single owner of service lifecycle policy.
• The CLI and updater no longer need to know raw control endpoints, payload shapes, or status keys.
• Backend/WebUI process details live behind adapters, keeping restart/backoff policy separate from platform/process implementation.

Test Plan

• uv run pytest tests/updater/test_updater.py tests/cli/test_service_manager.py tests/cli/test_service_commands.py
• uv run ruff check flocks/cli/service_config.py flocks/cli/service_control.py flocks/cli/service_process.py flocks/cli/service_supervisor.py flocks/cli/service_manager.py flocks/cli/main.py flocks/updater/updater.py tests/cli/test_service_manager.py tests/cli/test_service_commands.py tests/updater/test_updater.py
• git diff --check

Compatibility, Migration & Rollback

• No migration is required for normal users.
• Rollback is to revert this PR and return CLI service management to the previous lifecycle implementation.
• Existing logs remain under the same backend/WebUI paths, with supervisor logs kept separately.